﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>ASP.NET Boilerplate</title>
<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
</head>

<body>

<div class="document-contents">

<h3>Introduction</h3>
<p><strong>OData</strong> is defined as "An <strong>open protocol</strong> to 
allow the creation and consumption of <strong>queryable</strong> and <strong>
interoperable RESTful APIs</strong> in a <strong>simple</strong> and <strong>
standard</strong> way" in <a href="http://www.odata.org/" target="_blank">
odata.org</a>. You can use OData with ASP.NET Boilerplate.
<a href="https://www.nuget.org/packages/Abp.Web.Api.OData" target="_blank">
Abp.Web.Api.OData</a> nuget package simplifies it's usage.</p>
	<h3>Setup</h3>
	<h4>Install Nuget Package</h4>
	<p>We should first install Abp.Web.Api.OData nuget package to our WebApi 
	project:</p>
	<pre>Install-Package Abp.Web.Api.OData</pre>
	<h4>Set Module Dependency</h4>
	<p>We should set dependency to AbpWebApiODataModule from our module. 
	Example:</p>
	<pre lang="cs"><strong>[DependsOn(typeof(AbpWebApiODataModule))]</strong>
public class MyProjectWebApiModule : AbpModule
{
    ...
}</pre>
	<p>See <a href="/Pages/Documents/Module-System">module system</a> to 
	understand module dependencies.</p>
	<h4>Configure Your Entities</h4>
	<p>OData requires to declare entities which can be used as OData resources. 
	We should do this in
	<a href="/Pages/Documents/Module-System#DocModulePreInit">PreInitialize</a> 
	method of our module, as shown below:</p>
	<pre lang="cs">[DependsOn(typeof(AbpWebApiODataModule))]
public class MyProjectWebApiModule : AbpModule
{
    public override void PreInitialize()
    {
        var builder = Configuration.Modules.AbpWebApiOData().ODataModelBuilder;

        //Configure your entities here...
        <strong>builder.EntitySet&lt;Person&gt;(&quot;Persons&quot;);</strong>
    }

    ...
}</pre>
	<p>Here, we got the ODataModelBuilder reference and set the Person entity. 
	You can use EntitySet to add other entities as similar. See
	<a href="http://www.asp.net/web-api/overview/odata-support-in-aspnet-web-api/odata-v4/create-an-odata-v4-endpoint" target="_blank">
	OData documentation</a> for more information on builder.</p>
	<h3>Create Controllers</h3>
	<p>Abp.Web.Api.OData nuget package includes <strong>AbpODataEntityController</strong> 
	base class (which extends standard ODataController) to create your controllers easier. An example to create an OData 
	endpoint for Person entity:</p>
	<pre lang="cs">public class PersonsController : <strong>AbpODataEntityController&lt;Person&gt;</strong>
{
    public PersonsController(<strong>IRepository&lt;Person&gt; repository</strong>)
        : base(repository)
    {
    }
}</pre>
	<p>It's that easy. All methods of AbpODataEntityController is <strong>
	virtual</strong>. That means you can override <strong>Get</strong>, <strong>
	Post</strong>, <strong>Put</strong>, <strong>Patch</strong>, <strong>Delete</strong> 
	and other actions and add your own logic.</p>
	<h3>Examples</h3>
	<p>Here, some example requests to the controller defined above. Assume that 
	the application works on <em>http://localhost:61842</em>. We will show some 
	basics. Since OData is a standard protocol, you can easily find more 
	advanced examples on the web.</p>
	<h4>Getting List of Entities</h4>
	<p>Getting all people.</p>
	<h5>Request</h5>
	<pre>GET http://localhost:61842/odata/Persons</pre>
	<h5>Response</h5>
	<pre lang="js">{
  &quot;@odata.context&quot;:&quot;http://localhost:61842/odata/$metadata#Persons&quot;,&quot;value&quot;:[
    {
      &quot;Name&quot;:&quot;Douglas Adams&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:1
    },{
      &quot;Name&quot;:&quot;John Nash&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:2
    }
  ]
}</pre>
	<h4>Getting a Single Entity</h4>
	<p>Getting the person with Id = 2.</p>
	<h5>Request</h5>
	<pre>GET http://localhost:61842/odata/Persons(2)</pre>
	<h5>Response</h5>
	<pre lang="js">{
  &quot;@odata.context&quot;:&quot;http://localhost:61842/odata/$metadata#Persons/$entity&quot;,&quot;Name&quot;:&quot;John Nash&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:2
}</pre>
	<h4>Getting a Single Entity With Navigation Properties</h4>
	<p>Getting the person with Id = 1 including his phone numbers.</p>
	<h5>Request</h5>
	<pre>GET http://localhost:61842/odata/Persons(1)?$expand=Phones</pre>
	<h5>Response</h5>
	<pre lang="js">{
  &quot;@odata.context&quot;:&quot;http://localhost:61842/odata/$metadata#Persons/$entity&quot;,&quot;Name&quot;:&quot;Douglas Adams&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:1,&quot;Phones&quot;:[
    {
      &quot;PersonId&quot;:1,&quot;Type&quot;:&quot;Mobile&quot;,&quot;Number&quot;:&quot;4242424242&quot;,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:1
    },{
      &quot;PersonId&quot;:1,&quot;Type&quot;:&quot;Mobile&quot;,&quot;Number&quot;:&quot;2424242424&quot;,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:2
    }
  ]
}</pre>
	<h4>Querying</h4>
	<p>Here, a more advanced query includes filtering, sorting and getting top 2 
	results.</p>
	<h5>Request</h5>
	<pre>GET http://localhost:61842/odata/Persons?$filter=Name eq &#39;Douglas Adams&#39;&amp;$orderby=CreationTime&amp;$top=2</pre>
	<h5>Response</h5>
	<pre lang="js">{
  &quot;@odata.context&quot;:&quot;http://localhost:61842/odata/$metadata#Persons&quot;,&quot;value&quot;:[
    {
      &quot;Name&quot;:&quot;Douglas Adams&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2015-11-07T20:12:39.363+03:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:1
    },{
      &quot;Name&quot;:&quot;Douglas Adams&quot;,&quot;IsDeleted&quot;:false,&quot;DeleterUserId&quot;:null,&quot;DeletionTime&quot;:null,&quot;LastModificationTime&quot;:null,&quot;LastModifierUserId&quot;:null,&quot;CreationTime&quot;:&quot;2016-01-12T20:29:03+02:00&quot;,&quot;CreatorUserId&quot;:null,&quot;Id&quot;:3
    }
  ]
}</pre>
	<p>OData supports paging, sorting, filtering, projections and much more. See
	<a href="http://www.odata.org/" target="_blank">it's own documentation</a> 
	for more information.</p>
	<h4>Creating a New Entity</h4>
	<p>In this example, we're creating a new person.</p>
	<h5>Request</h5>
	<pre><strong>POST</strong> http://localhost:61842/odata/Persons
	
{
    Name: "Galileo Galilei"
}</pre>
	<p>Here, "Content-Type" header is "application/json".</p>
	<h5>Response</h5>
	<pre lang="js">{
  &quot;@odata.context&quot;: &quot;http://localhost:61842/odata/$metadata#Persons/$entity&quot;,
  &quot;Name&quot;: &quot;Galileo Galilei&quot;,
  &quot;IsDeleted&quot;: false,
  &quot;DeleterUserId&quot;: null,
  &quot;DeletionTime&quot;: null,
  &quot;LastModificationTime&quot;: null,
  &quot;LastModifierUserId&quot;: null,
  &quot;CreationTime&quot;: &quot;2016-01-12T20:36:04.1628263+02:00&quot;,
  &quot;CreatorUserId&quot;: null,
  &quot;Id&quot;: 4
}</pre>
	<p>If we get the list again, we can see the new person. We can also update 
	or delete an existing entity as OData supports it.</p>
	<h4>Getting MetaData</h4>
	<p>We can get metadata of entities, as shown in this example.</p>
	<h5>Request</h5>
	<pre>GET http://localhost:61842/odata/$metadata</pre>
	<h5>Response</h5>
	<pre lang="xml">&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;

&lt;edmx:Edmx Version=&quot;4.0&quot; xmlns:edmx=&quot;http://docs.oasis-open.org/odata/ns/edmx&quot;&gt;
  
    &lt;edmx:DataServices&gt;
    
        &lt;Schema Namespace=&quot;AbpODataDemo.People&quot; xmlns=&quot;http://docs.oasis-open.org/odata/ns/edm&quot;&gt;
      
            &lt;EntityType Name=&quot;Person&quot;&gt;
        
                &lt;Key&gt;
          
                    &lt;PropertyRef Name=&quot;Id&quot; /&gt;
        
                &lt;/Key&gt;
        
                &lt;Property Name=&quot;Name&quot; Type=&quot;Edm.String&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;IsDeleted&quot; Type=&quot;Edm.Boolean&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;DeleterUserId&quot; Type=&quot;Edm.Int64&quot; /&gt;
        
                &lt;Property Name=&quot;DeletionTime&quot; Type=&quot;Edm.DateTimeOffset&quot; /&gt;
        
                &lt;Property Name=&quot;LastModificationTime&quot; Type=&quot;Edm.DateTimeOffset&quot; /&gt;
        
                &lt;Property Name=&quot;LastModifierUserId&quot; Type=&quot;Edm.Int64&quot; /&gt;
        
                &lt;Property Name=&quot;CreationTime&quot; Type=&quot;Edm.DateTimeOffset&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;CreatorUserId&quot; Type=&quot;Edm.Int64&quot; /&gt;
        
                &lt;Property Name=&quot;Id&quot; Type=&quot;Edm.Int32&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;NavigationProperty Name=&quot;Phones&quot; Type=&quot;Collection(AbpODataDemo.People.Phone)&quot; /&gt;
      
            &lt;/EntityType&gt;
      
            &lt;EntityType Name=&quot;Phone&quot;&gt;
        
                &lt;Key&gt;
          
                    &lt;PropertyRef Name=&quot;Id&quot; /&gt;
        
                &lt;/Key&gt;
        
                &lt;Property Name=&quot;PersonId&quot; Type=&quot;Edm.Int32&quot; /&gt;
        
                &lt;Property Name=&quot;Type&quot; Type=&quot;AbpODataDemo.People.PhoneType&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;Number&quot; Type=&quot;Edm.String&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;CreationTime&quot; Type=&quot;Edm.DateTimeOffset&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;Property Name=&quot;CreatorUserId&quot; Type=&quot;Edm.Int64&quot; /&gt;
        
                &lt;Property Name=&quot;Id&quot; Type=&quot;Edm.Int32&quot; Nullable=&quot;false&quot; /&gt;
        
                &lt;NavigationProperty Name=&quot;Person&quot; Type=&quot;AbpODataDemo.People.Person&quot;&gt;
          
                    &lt;ReferentialConstraint Property=&quot;PersonId&quot; ReferencedProperty=&quot;Id&quot; /&gt;
        
                &lt;/NavigationProperty&gt;
      
            &lt;/EntityType&gt;
      
            &lt;EnumType Name=&quot;PhoneType&quot;&gt;
        
                &lt;Member Name=&quot;Unknown&quot; Value=&quot;0&quot; /&gt;
        
                &lt;Member Name=&quot;Mobile&quot; Value=&quot;1&quot; /&gt;
        
                &lt;Member Name=&quot;Home&quot; Value=&quot;2&quot; /&gt;
        
                &lt;Member Name=&quot;Office&quot; Value=&quot;3&quot; /&gt;
      
            &lt;/EnumType&gt;
    
        &lt;/Schema&gt;
    
        &lt;Schema Namespace=&quot;Default&quot; xmlns=&quot;http://docs.oasis-open.org/odata/ns/edm&quot;&gt;
      
            &lt;EntityContainer Name=&quot;Container&quot;&gt;
        
                &lt;EntitySet Name=&quot;Persons&quot; EntityType=&quot;AbpODataDemo.People.Person&quot; /&gt;
      
            &lt;/EntityContainer&gt;
    
        &lt;/Schema&gt;
  
    &lt;/edmx:DataServices&gt;

&lt;/edmx:Edmx&gt;</pre>
<p>Metadata is used to investigate the service.</p>

	<h3>Sample Project</h3>
	<p>You get source code of the sample project here: 	<a href="https://github.com/aspnetboilerplate/sample-odata">https://github.com/aspnetboilerplate/sample-odata</a></p>

</div>

</body>

</html>
